[cross_file] Clarify MIME type docs by mackings · Pull Request #11727 · flutter/packages

mackings · 2026-05-18T09:06:05Z

Clarifies the cross_file documentation for XFile.mimeType.

This PR documents that mimeType is not inferred from the file path or file contents. It is only available when provided while creating the XFile, or when available from the platform-backed file.

Fixes flutter/flutter#93379

Test exemption: This is a documentation-only change that clarifies existing API behavior, so no new tests were added.

Validation run:

dart analyze
dart test
dart test test/readme_excerpts_test.dart

Pre-Review Checklist

gemini-code-assist

Code Review

This pull request updates the documentation for XFile to clarify that the mimeType property is not automatically inferred from file paths or contents. These updates are reflected in the CHANGELOG.md, README.md, and the base and IO implementations of XFile. Feedback was provided to improve the clarity of the documentation in the XFile constructors by explicitly stating that the mimeType is only available if passed to the constructor, and to ensure consistency by applying similar updates to the HTML implementation.

gemini-code-assist · 2026-05-18T09:07:42Z

+  /// [mimeType] is not inferred from [path] and is returned from [mimeType]
+  /// only if explicitly passed.


The phrasing "returned from [mimeType]" is confusing because [mimeType] is used for both the parameter and the property in this context. It would be clearer to state that the property is only available if the parameter is provided. Additionally, for consistency, please consider applying similar documentation updates to the XFile constructors in lib/src/types/html.dart.

Suggested change

/// [mimeType] is not inferred from [path] and is returned from [mimeType]

/// only if explicitly passed.

/// [mimeType] is not inferred from [path] and is only available if explicitly

/// passed to the constructor.

I updated the wording in io.dart and added matching constructor documentation in html.dart. Tests still pass.

gemini-code-assist · 2026-05-18T09:07:42Z

@@ -40,6 +43,8 @@ class XFile extends XFileBase {

  /// Construct an CrossFile from its data
  ///
+  /// [mimeType] is returned from [mimeType] only if explicitly passed.


The phrasing "returned from [mimeType]" is redundant. It's clearer to specify that the value is only available if provided during construction.

Suggested change

/// [mimeType] is returned from [mimeType] only if explicitly passed.

/// [mimeType] is only available if explicitly passed to the constructor.

stuartmorgan-g · 2026-05-18T14:40:09Z

Thanks for the contribution! You’ve checked boxes in the PR checklist above that are not reflected in this PR, so I’m assuming this is a work in progress and am marking it as a Draft. Please review the checklist, updating the PR as appropriate, and when the state of the PR as posted reflects the checklist please feel free to mark it as ready for review.

gemini-code-assist

Code Review

This pull request updates the documentation for XFile to specify that mimeType is not inferred from file paths or contents. The review feedback suggests refining the language for clarity and consistency across platforms, specifically by removing references to platform-backed files and explicitly stating the lack of inference in all relevant constructors.

gemini-code-assist · 2026-05-19T12:43:01Z

+  /// The value is not inferred from the file contents or path. It is only
+  /// available if provided when the [XFile] was created, or if available from
+  /// the platform-backed file.


The phrase "or if available from the platform-backed file" is potentially confusing. Since mimeType is a synchronous getter and the implementations in this package only return the value provided during construction, this phrase might lead users to expect some form of automatic detection for certain files. It's clearer to state that it must be provided at creation, which covers both manual instantiation and cases where a platform plugin provides the value.

Suggested change

/// The value is not inferred from the file contents or path. It is only

/// available if provided when the [XFile] was created, or if available from

/// the platform-backed file.

/// The value is not inferred from the file contents or path. It is only

/// available if provided when the [XFile] was created.

gemini-code-assist · 2026-05-19T12:43:01Z

+The `mimeType` property is not inferred from the file path or contents. It is
+only available if provided when the `XFile` was created, or if available from the
+platform-backed file.


Similar to the base class documentation, the mention of "platform-backed file" here is redundant and may cause confusion regarding whether the MIME type is automatically detected in some scenarios. Simplifying this to focus on the requirement of providing it at creation improves clarity.

Suggested change

The `mimeType` property is not inferred from the file path or contents. It is

only available if provided when the `XFile` was created, or if available from the

platform-backed file.

The `mimeType` property is not inferred from the file path or contents. It is

only available if provided when the `XFile` was created.

gemini-code-assist · 2026-05-19T12:43:01Z

  /// `name` needs to be passed from the outside, since it's only available
  /// while handling [html.File]s (when the ObjectUrl is created).
+  ///
+  /// [mimeType] is only available if explicitly passed to the constructor.


For consistency with the io implementation and to be explicitly clear, it's helpful to mention that the MIME type is not inferred from the path (which is a Blob URL on web).

Suggested change

/// [mimeType] is only available if explicitly passed to the constructor.

/// [mimeType] is not inferred from [path] and is only available if explicitly

/// passed to the constructor.

gemini-code-assist · 2026-05-19T12:43:01Z


  /// Construct an CrossFile from its data
  ///
+  /// [mimeType] is only available if explicitly passed to the constructor.


This constructor also accepts an optional path. For consistency with the main XFile constructor in this file, it should explicitly state that the MIME type is not inferred from that path.

Suggested change

/// [mimeType] is only available if explicitly passed to the constructor.

/// [mimeType] is not inferred from [path] and is only available if explicitly

/// passed to the constructor.

stuartmorgan-g · 2026-05-19T15:28:39Z

I followed [the version and CHANGELOG instructions], using [semantic versioning] and the [repository CHANGELOG style], or I have commented below to indicate which documented exception this PR falls under[^1].

I don't see any changes addressing this item.

mackings · 2026-05-19T16:01:38Z

Oh wow, that's an error on my end. I will update the PR checks. [image: GeoTrack] <https://geotrack.email/?utm_source=gmail&utm_medium=signature&utm_campaign=viralSignature> Sender notified with GeoTrack <https://geotrack.email/?utm_source=gmail&utm_medium=signature&utm_campaign=viralSignature> [image: 1]

…

On Tue, May 19, 2026 at 4:29 PM stuartmorgan-g ***@***.***> wrote: *stuartmorgan-g* left a comment (flutter/packages#11727) <#11727 (comment)> - I followed [the version and CHANGELOG instructions], using [semantic versioning] and the [repository CHANGELOG style], or I have commented below to indicate which documented exception this PR falls under[^1]. I don't see any changes addressing this item. — Reply to this email directly, view it on GitHub <#11727 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALUEMUBTOREB4B4W2TH6DC343R4UVAVCNFSM6AAAAACZCKLOV2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DIOBZGM2DCNRQGU> . You are receiving this because you authored the thread.Message ID: ***@***.***>

gemini-code-assist

Code Review

This pull request clarifies that the mimeType property in the cross_file package is not inferred from the file path or contents. Documentation updates reflecting this behavior were made in the CHANGELOG.md, README.md, and the XFile class across its base, HTML, and IO implementations. I have no feedback to provide.

stuartmorgan-g · 2026-05-19T18:29:46Z

I will update the PR checks.

It appears that your change was to delete the checklist item. Could you explain why you believe that our required contribution steps do not apply to this PR?

mackings · 2026-05-19T20:01:02Z

You’re right, I misunderstood that checklist item earlier. I’ve updated the PR to follow the version and CHANGELOG process now: - bumped the package version in `pubspec.yaml.` - updated the package `CHANGELOG.md` with the release heading and entry - restored the checklist item in the PR description

…

On Tue, May 19, 2026, 7:30 PM stuartmorgan-g ***@***.***> wrote: *stuartmorgan-g* left a comment (flutter/packages#11727) <#11727 (comment)> I will update the PR checks. It appears that your change was to delete the checklist item. Could you explain why you believe that our required contribution steps do not apply to this PR? — Reply to this email directly, view it on GitHub <#11727 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALUEMUFWBYFFTVQQCDKHS5T43SR3DAVCNFSM6AAAAACZCKLOV2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DIOJQHAZDKOBVGE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

github-actions Bot added the p: cross_file label May 18, 2026

gemini-code-assist Bot reviewed May 18, 2026

View reviewed changes

mackings force-pushed the docs-cross-file-mimetype branch from ddb605b to 1a79271 Compare May 18, 2026 09:37

stuartmorgan-g marked this pull request as draft May 18, 2026 14:40

mackings marked this pull request as ready for review May 19, 2026 12:41

gemini-code-assist Bot reviewed May 19, 2026

View reviewed changes

stuartmorgan-g marked this pull request as draft May 19, 2026 15:28

stuartmorgan-g changed the title ~~Clarify cross_file MIME type docs~~ [cross_file] Clarify MIME type docs May 19, 2026

stuartmorgan-g mentioned this pull request May 19, 2026

[camera] Fix web facingMode capability handling #11728

Open

11 tasks

mackings marked this pull request as ready for review May 19, 2026 16:03

gemini-code-assist Bot reviewed May 19, 2026

View reviewed changes

Clarify cross_file MIME type docs

df9109d

mackings force-pushed the docs-cross-file-mimetype branch from ea8232e to df9109d Compare May 19, 2026 19:47

Merge branch 'main' into docs-cross-file-mimetype

9e8ba06

stuartmorgan-g self-requested a review May 20, 2026 10:58

Merge branch 'main' into docs-cross-file-mimetype

56cb3ea

		/// [mimeType] is not inferred from [path] and is returned from [mimeType]
		/// only if explicitly passed.

	/// [mimeType] is returned from [mimeType] only if explicitly passed.
	/// [mimeType] is only available if explicitly passed to the constructor.

	/// [mimeType] is only available if explicitly passed to the constructor.
	/// [mimeType] is not inferred from [path] and is only available if explicitly
	/// passed to the constructor.

Conversation

mackings commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-Review Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 18, 2026

Choose a reason for hiding this comment

Uh oh!

mackings May 18, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 18, 2026

Choose a reason for hiding this comment

Uh oh!

stuartmorgan-g commented May 18, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 19, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 19, 2026

Choose a reason for hiding this comment

Uh oh!

stuartmorgan-g commented May 19, 2026

Uh oh!

mackings commented May 19, 2026 via email

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

stuartmorgan-g commented May 19, 2026

Uh oh!

mackings commented May 19, 2026 via email • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mackings commented May 18, 2026 •

edited

Loading

mackings commented May 19, 2026 via email •

edited

Loading